嗨大家，我是 Debuguy。

昨天我們成功用 LiteLLM 把 API Key 安全和成本控制問題解決了，但還有一個更大的問：生產環境的可觀測性。

Day 15 時我們就討論過，GenKit Developer UI 很棒，但它只適合開發環境，不適合生產環境。今天，我們要把整套系統接上 Langfuse，建立真正的生產級可觀測性。

程式碼異動

import 'dotenv/config';
import { genkit, z } from 'genkit';
import { liteLlm } from './plugin/litellm.js';
import { startFlowServer } from '@genkit-ai/express';
+ import { NodeSDK } from "@opentelemetry/sdk-node";
+ import { LangfuseSpanProcessor } from "@langfuse/otel";

+ new NodeSDK({
+  spanProcessors: [new LangfuseSpanProcessor()],
+ }).start();

async function startGenkitFlow() {
  const ai = genkit({
    plugins: [
      liteLlm(),
    ],
  });
  
  // ... Flow 定義（完全不用改）
}

發現了嗎？

整合 Langfuse 只需要加 5 行程式碼！這就是 OpenTelemetry 標準的威力。

為什麼這麼簡單？

GenKit 內建 OpenTelemetry 支援

GenKit 從一開始就基於 OpenTelemetry 設計，它會自動產生 trace 資料：

• 每個 Flow 執行
• 每個 LLM 呼叫
• 每個 Tool 使用
• Token 使用統計

這些資料都符合 OpenTelemetry 標準格式。

Langfuse 的 OTEL Processor

@langfuse/otel 套件提供了一個 LangfuseSpanProcessor，它會：

1. 攔截所有 OpenTelemetry 的 Span
2. 轉換成 Langfuse 的格式
3. 自動上傳到 Langfuse

我們只需要告訴 OpenTelemetry SDK：「請用這個 Processor」

new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
}).start();

就這樣，完成了！

環境變數配置

當然，Langfuse 需要知道要把資料送到哪裡，這些透過環境變數設定：

LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
LANGFUSE_BASE_URL=http://localhost:3000

這些變數會被 LangfuseSpanProcessor 自動讀取。

package.json 的變化

Day 17 新增了兩個 dependencies：

{
  "dependencies": {
    // ... 原有的套件
    "@langfuse/otel": "^4.2.0",              // Langfuse OTEL 整合
    "@opentelemetry/sdk-node": "^0.205.0",   // OpenTelemetry SDK
  }
}

Docker Compose 的變化

Day 17 的 docker-compose.yml 新增了完整的 Langfuse stack：

services:
  # ... 原有的服務 (slack-bolt, genkit-service, litellm...)
  
  # Day 17 新增：Langfuse 相關服務
  langfuse-web:
    image: docker.io/langfuse/langfuse:3
    ports:
      - 3000:3000
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
      REDIS_HOST: redis
      CLICKHOUSE_URL: http://clickhouse:8123
      # ... 其他配置
  
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:3
    # 處理背景任務和資料彙整
  
  postgres:
    image: postgres:17
    # 儲存 Langfuse 的 metadata
  
  clickhouse:
    image: clickhouse/clickhouse-server
    # 儲存大量的 trace 資料
  
  redis:
    image: redis:7
    # 快取和任務佇列
  
  minio:
    image: minio/minio
    # 儲存大型檔案和 exports

Langfuse 的架構：

• Web：提供 UI 介面
• Worker：背景處理和資料彙整
• Postgres：儲存結構化數據（專案、使用者、設定）
• ClickHouse：儲存大量 trace 資料（高效能時序資料庫）
• Redis：快取和任務佇列
• MinIO：S3 相容的物件儲存

實際效果驗證

Step 1: 啟動所有服務

docker-compose up -d

等所有服務健康檢查通過後（可能需要 1-2 分鐘）。

Step 2: 初始化 Langfuse

開啟瀏覽器訪問 http://localhost:3000，第一次會要求你建立帳號、組織、專案。

最後生成 API Key

更新到 .env 檔案中。

Step 3: 測試系統

在 Slack 中 mention 你的 bot，發送一個測試訊息：

@bot 測試 Langfuse 整合

就可以在 Langfuse 中看到美美的 trace 了

小結

基礎設施層面：

• 新增 Langfuse stack (web, worker, postgres, clickhouse, redis, minio)
• 配置環境變數 (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY)

得到的效果：

• ✅ 完整的 trace 記錄
• ✅ 視覺化的 Flow 執行流程
• ✅ Token 使用和成本統計
• ✅ 錯誤追蹤和告警
• ✅ 效能分析和瓶頸識別
• ✅ Self-hosted，資料完全掌控

這就是選擇符合標準的工具的好處：OpenTelemetry 讓我們可以用最小的程式碼變動，換來生產級的可觀測性。

從 Day 16 的 LiteLLM（安全 + 成本控制）到 Day 17 的 Langfuse（可觀測性），我們的系統已經具備了在生產環境運行的基本條件。

明天我們要來聊聊另一個實務話題：測試與評估。當你有了完整的 trace 資料後，如何建立測試資料集和評估機制，確保 ChatBot 的品質？

完整的原始碼在這裡，包含完整的 docker-compose 配置和 Langfuse 整合！

AI 的發展變化很快，目前這個想法以及專案也還在實驗中。但也許透過這個過程大家可以有一些經驗和想法互相交流，歡迎大家追蹤這個系列。

也歡迎追蹤我的 Threads @debuguy.dev